[docs] Add GTK+3 migration guide

diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index a9ca65d370bb4473435996014497d34ba2dba396..3e3df0d2b685d74244fe5173365ed72909a728ba 100644 (file)
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -126,6 +126,7 @@ content_files =                                     \
        directfb.sgml                           \
        drawing-model.xml                       \
        glossary.xml                            \
+       migrating-2to3.xml                      \
        migrating-checklist.sgml                \
         migrating-ClientSideWindows.sgml       \
        migrating-GtkAboutDialog.sgml           \
@@ -157,6 +158,7 @@ content_files =                                     \
 expand_content_files =                                 \
        drawing-model.xml                       \
        glossary.xml                            \
+       migrating-2to3.xml                      \
        migrating-checklist.sgml                \
         migrating-ClientSideWindows.sgml       \
        migrating-GtkAction.sgml                \

diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 24595fa4f922f06745801f4c0a3bcbac9739d3eb..bb2b630dc29b494186085e157db2a0d7bb3870cb 100644 (file)
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -400,6 +400,7 @@ that is, GUI components such as #GtkButton or #GtkTextView.
       </para>
     </partintro>
 
+    <xi:include href="migrating-2to3.xml" />
     <xi:include href="xml/migrating-checklist.sgml" />
     <xi:include href="changes-1.2.sgml" />
     <xi:include href="changes-2.0.sgml" />

diff --git a/docs/reference/gtk/migrating-2to3.xml b/docs/reference/gtk/migrating-2to3.xml
new file mode 100644 (file)
index 0000000..7ef2b3c
--- /dev/null
+++ b/docs/reference/gtk/migrating-2to3.xml
@@ -0,0 +1,69 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<chapter id="gtk-migrating-2-to-3">
+  <title>Migrating from 2.x to 3.x</title>
+
+  <refsect1>
+  <title>Only single includes</title>
+  <para>
+    Make sure your program only include the toplevel headers:
+    <programlisting>
+    make CFLAGS+="-DG_DISABLE_SINGLE_INCLUDES -DGDK_PIXBUF_DISABLE_SINGLE_INCLUDES -DGTK_DISABLE_SINGLE_INCLUDES"
+    </programlisting>
+  </para>
+  </refsect1>
+
+  <refsect1>
+  <title>Do not use deprecated symbols</title>
+  <para>
+    Make sure your program doesn't use any deprecated functions:
+    <programlisting>
+    make CFLAGS+="-DG_DISABLE_DEPRECATED -DGDK_PIXBUF_DISABLE_DEPRECATED -DGDK_DISABLE_DEPRECATED -DGTK_DISABLE_DEPRECATED"
+    </programlisting>
+  </para>
+  </refsect1>
+
+  <refsect1>
+  <title>Use accessor funcions instead direc access</title>
+  <para>
+    GTK+ 3 removed many implementation details and struct members from
+    its public headers. To ensure that your application will not have problems
+    with this, you can define the preprocessor symbol GSEAL_ENABLE. This will
+    make the compiler catch all uses of direct access to struct fields so that
+    you can go through them one by one and replace them with a call to an
+    accessor function instead.
+    <programlisting>
+    make CFLAGS+="-DGSEAL_ENABLE"
+    </programlisting>
+  </para>
+  </refsect1>
+
+  <refsect1>
+  <title>GTK+ Modules</title>
+  <para>
+    Some GNOME modules install GTK+ modules. Since GTK+ 3 will be
+    parallel-installable with GTK+ 2.x, the two have separate locations for
+    their loadable modules. The location for GTK+ 2.x is $libdir/gtk-2.0
+    (and its subdirectories), for GTK+ 3, the location is $libdir/gtk-3.0
+    (and its subdirectories).
+  </para>
+  <para>
+    For some kinds of modules, namely im modules and pixbuf loaders,
+    GTK+ keeps a cache file with extra information about the modules.
+    These cache files are located in $sysconfdir/gtk-2.0 for GTK+ 2.x.
+    For GTK+ 3, they have been moved to $libdir/gtk-3.0/3.0.0/.
+    The commands that create these cache files have been renamed with a -3
+    suffix to make them parallel-installable.
+  </para>
+  <para>
+    Note that GTK+ modules often link against libgtk, libgdk-pixbuf, etc.
+    If that is the case for your module, you have to be careful to link the
+    GTK+ 2.x version of your module against the 2.x version of the libraries,
+    and the GTK+ 3 version against hte 3.x versions. Loading a module linked
+    against libgtk 2.x into an application using GTK+ 3 will lead to
+    unhappiness and must be avoided.
+  </para>
+  </refsect1>
+</chapter>